 
  

 






<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 
<html>

<!-- Mirrored from www.javapractices.com/topic/TopicAction.do?Id=171 by HTTrack Website Copier/3.x [XR&CO'2010], Sun, 12 Jun 2011 17:28:07 GMT -->
<!-- Added by HTTrack --><meta http-equiv="content-type" content="text/html;charset=UTF-8"><!-- /Added by HTTrack -->
<head>
 <title>
  Java Practices -> Avoid @throws in javadoc
 </title>
 <link rel="stylesheet" type="text/css" href="../stylesheet8.css" media="all">
 
 <link rel="shortcut icon" href='../images/favicon.ico' type="image/vnd.microsoft.icon">
 <meta name="description" content="Concise presentations of java programming practices, tasks, and conventions, amply illustrated with syntax highlighted code examples.">
 
 <meta name='keywords' content='java,java programming,java practices,java idiom,java style,java design patterns,java coding conventions,'>
 
 
</head>
 
<body>


<div class='menu-bar'>
 
  <a href='../home/HomeAction.html' title='Table of Contents'>Home</a> |
  <a href='../vote/VoteSummaryAction-2.html' title='View Poll Results'>Poll</a> |
   
  <A href='../feedback/FeedbackAction451f-2.html?Operation=Show' title='Send Your Feedback'>Wiki</a> |
  <b><a href='../source/SourceAction-2.html' title='Grab Source Code'>Source Code</a></b><IMG class='no-margin' SRC="../images/goldstar.gif" ALT=""> |

  <a href='http://www.web4j.com/Java_Web_Application_Framework_Overview.jsp?From=1' title='Free Download - Java Web Application Framework'><b>WEB4J</b></a> |
  
  <a href='http://www.date4j.net/' title='Replacement for java.util.Date'><b>DATE4J</b></a> |

   <a href='../references/ReferencesAction-2.html' title='References'>Links</a>
   
  <form action='http://www.javapractices.com/search/SearchAction.do' method='get' class='search-form'>
   <input type='text' name='SearchTerms' value="" size=12 maxlength=50 class='search'>
   <input type='submit' value="Search">
  </form>
 
</div>

<P>



  

 






<p class="display-messages">

 

 

</p>


<div class="main-layout">
 
   

 




<div class='page-title'>Avoid @throws in javadoc</div>

<div class='main-body'>
 
<br>Some argue that <tt>@throws</tt> should not be used at all.
Instead, one may simply rely on the javadoc tool to automatically document all exceptions placed in the <tt>throws</tt> clause.
However, <a href='TopicActionf005-2.html?Id=44'>others disagree</a>.

<p>Checked Exceptions :
<ul>
 <li>declaring <em>only</em> checked exceptions in the method's <tt>throws</tt> clause is a widely followed convention
 <li>javadoc automatically generates basic documentation for all exceptions in the <tt>throws</tt> clause
 <li>the documentation is generated with no extra effort on your part
</ul>

Unchecked Exceptions :
<ul>
 <li>aren't typically placed in the method's <tt>throws</tt> clause.
 <li>are very rarely caught by the caller.</li>
 <li>do not form part of the <a href="TopicAction63b6-2.html">contract</a> of the method,
 but rather represent what happens when the <a href="TopicAction5ff3-2.html">contract is broken</a>. The caller cannot recover from such errors.</li>
 <li>almost always occur when a precondition on a parameter is not met. However, such conditions are 
 <em>almost always already documented</em> in a <tt>@param</tt> tag.
</ul>

Therefore, if you :
<ul>
 <li>only place checked exceptions in the throws clause
 <li>don't use <tt>@throws</tt> at all
</ul>

then only <em>checked</em> exceptions will appear in javadoc. 
It can be argued that this is beneficial: since checked exceptions are more important than unchecked ones, 
it's best that they stand out in javadoc, without being mixed in with other exceptions of minor interest.
 

<P>In almost all cases, a <tt>@throws</tt> tag simply <em>repeats verbatim</em> conditions already stated
in a <tt>@param</tt> tag, and doesn't add in any way to the specification
of the method's behavior. Such repetition should be regarded with grave suspicion. 
When a change occurs, it's far too easy to forget to update the javadoc in two separate places. 

<p>A general comment regarding broken contracts can be stated once in the
javadoc <tt>overview.html</tt> document :
<br><em>"If the requirements or promises of any method's contract are not fulfilled
(that is, if there is a bug in either the method or its caller), then an
unchecked exception will be thrown. The precise type of such an unchecked
exception does not form part of any method's contract."</em>


<p><b>Example</b>
<p><tt>BasketBall</tt> has two constructors.
<p>The first constructor includes several <tt>@throws</tt> tags in its
javadoc. However, aside from the type of the unchecked exception, all of
these <tt>@throws</tt> tags are logically equivalent to some previous statement
in a <tt>@param</tt> tag. They add nothing to the contract.
<p>The second constructor follows a different style. It has a single parameter,
and the conditions on this parameter are stated once (and once only) in
its <tt>@param</tt> tag.
<br>
<PRE>

<span class='keyword'>public</span> <span class='keyword'>final</span> <span class='keyword'>class</span> BasketBall {

  <span class='comment'>/**
  * @param aManufacturer non-null and has visible content.
  * @param aDiameter in centimeters, in the range 1..50.
  * @throws IllegalArgumentException if aDiameter not in given range.
  * @throws IllegalArgumentException if aManufacturer has no visible content.
  * @throws NullPointerException if aManufacturer is null.
  */</span>
  BasketBall( String aManufacturer, <span class='keyword'>int</span> aDiameter ){
    <span class='comment'>//..elided
</span>  }

  <span class='comment'>/**
  * @param aDiameter in centimeters, in the range 1..50.
  */</span>
  BasketBall( <span class='keyword'>int</span> aDiameter ){
    <span class='comment'>//..elided
</span>  }

  <span class='comment'>// PRIVATE //
</span>  <span class='keyword'>private</span> String fManufacturer;
  <span class='keyword'>private</span> <span class='keyword'>int</span> fDiameter;
} 
</PRE>
<br>
<br>
<br>

</div>




<div class='topic-section'>See Also :</div>
<div class='main-body'>
 
  
  <a href='TopicActionf005-2.html?Id=44'>Javadoc all exceptions</a> <br>
 
  
  <a href='TopicAction63b6-2.html?Id=194'>Design by Contract</a> <br>
 
</div>


<div class='topic-section'>Would you use this technique?</div>
<div class='main-body'>
  
  <form action="http://www.javapractices.com/vote/AddVoteAction.do" method='post'>
    Yes<input type='radio' name='Choice' value='Y' >
    &nbsp;&nbsp;No<input type='radio' name='Choice' value='N'>
    &nbsp;&nbsp;Undecided<input type='radio' name='Choice' value="?" >
    &nbsp;&nbsp;<input type=submit value="Vote" >
    <input type='hidden' name='Operation' value='Apply'>
    <input type='hidden' name='TopicId' value='171'>
  </form>
</div>

<div style='height:10.0em;'></div>

 
 
</div>

  

 





<div align='center' class='legalese'>  
&copy; 2011 Hirondelle Systems |
<a href='../source/SourceAction-2.html'><b>Source Code</b></a><IMG class='no-margin' SRC="../images/goldstar.gif" ALT=""> |
<a href="mailto:webmaster@javapractices.com">Contact</a> |
<a href="http://creativecommons.org/licenses/by-nc-sa/1.0/">License</a> |
<a href='../apps/cjp.rss'>RSS</a>
<!-- ukey="2AC36CD2" -->
<!-- ckey="16DF3D87" -->
<br>

 Individual code snippets can be used under this <a href='../LICENSE.txt'>BSD license</a> - Last updated on June 6, 2010.<br>
 Over 150,000 unique IPs last month - <span title='Java Practices 2.6.5, Mon May 16 00:00:00 EDT 2011'>Built with</span> <a href='http://www.web4j.com/'>WEB4J</a>.<br>
 - In Memoriam : Bill Dirani -
</div>

<script src="../../www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-2633428-1";
urchinTracker();
</script>



</body>

<!-- Mirrored from www.javapractices.com/topic/TopicAction.do?Id=171 by HTTrack Website Copier/3.x [XR&CO'2010], Sun, 12 Jun 2011 17:28:07 GMT -->
<!-- Added by HTTrack --><meta http-equiv="content-type" content="text/html;charset=UTF-8"><!-- /Added by HTTrack -->
</html>
